/------------------------------------\
|             Bazound                |
|   Sound system configuration tool  |
|       Chris Bazley, 2003          |
| Version 0.06 (21st September 2003) |
\------------------------------------/
N.B. This text is best viewed at a display width of 77 columns.

-----------------------------------------------------------------------------
1   Introduction and Purpose
    ========================

  Bazound is a small configuration and diagnostic utility for the RISC OS
sound system. It may be useful to programmers writing sound software, and in
situations where programs have left the sound system in an indeterminate
state. It was written using AppBasic, a new programming aid that simplifies
the task of writing Toolbox applications in BASIC.

-----------------------------------------------------------------------------
2   Requirements
    ============

   RISC OS 3.10 or better.
   The Toolbox modules (in !System, or in ROM with RISC OS 3.6).

  If any of the above facilities are unavailable then the program will fail
to load, with an error message describing the problem.

-----------------------------------------------------------------------------
3   Quick Guide
    ===========

  Bazound provides two windows; a dialogue box to allow configuration of
the sound system (SELECT-click on the iconbar icon) and an information window
that shows the addresses of various sound system components (ADJUST-click on
the iconbar icon).

Sound configuration dbox
------------------------
  On computers with 16-bit sound the 'Sample rate (Hz)' selector takes
priority over the sample period in s, which will be greyed out. On machines
with 8-bit sound the converse will be true. This reflects the fact that the
16-bit sound hardware only supports a limited number of sample rates. If you
change one of these values then the other will be updated in parallel.

  The tuning value and volume will only affect those applications that use
the default Channel Handler (the 'SoundChannels' module). Similarly, the
tempo will only affect applications that actually use the Scheduler (e.g.
Maestro). However, even tracker players that completely supersede the
Channel Handler may reconfigure the number of channels, because it affects
the VIDC stereo image registers.

  Because one cannot read whether or not oversampling is enabled without
changing it, Bazound momentarily disables oversampling upon setting up
its dbox. In practice this should not be noticeable.

  To reconfigure the sound system using the displayed settings, click the
'OK' button (using ADJUST rather than SELECT if you want the dbox to remain
open). You can reset the displayed settings from the actual system
configuration at any time by ADJUST-clicking 'Cancel'.

Info window
-----------
  This window displays the contents of the Scheduler and Channel Handler
blocks, as returned by Sound_Configure, and the current 16 bit linear
handler. An expert user may be able to tell from this information whether
the default channel handler has been superseded by a sound tracker player,
for instance.

  The Channel Handler block is entitled '8 bit -law handler' because most
(all?) modules that replace the Channel Handler do so in order to talk
directly to the DMA handler, and do not provide facilities that are remotely
similar.

  The displayed 'Type' indicates whether 16 bit sound is supported or
only 8 bit -law, as reported by Sound_Mode 0. If 16 bit sound is supported
then further information will be displayed. This is derived from the flags
returned in R1 (which apparently correspond to bits 5 and 6 in CMOS RAM byte
132). I don't know how reliable this is, but paraphrasing PRM volume 5a:

- 'Master'/'slave' refers to the DAC clock vis-a-vis any external clock.
- If there is no external clock then only standard VIDC20 sample rates are
available, whereas with an external clock additional sample rates derived
from 44.1kHz are supported.
- If the DAC clock is master then this implies that a suitable clock driver
is installed.

  To update the display, click MENU over the window and then select the
'Refresh' entry from the pop up menu.

-----------------------------------------------------------------------------
4   Program history
    ===============

0.01 (18th August 2003)
   First version.

0.02 (21st August 2003)
   Added this help text, accessible via new 'Help...' menu entry or F1 key
    shortcut in the dialogue box.
   Implemented Return and Escape key shortcuts for the dbox action buttons.

0.03 (23rd August 2003)
   Moved informational displays from main dbox into new window. The contents
    of the Scheduler and Channel Handler blocks are now decoded and
    displayed. Parameter to linear handler is displayed, in addition to code
    address.
   Slightly more efficient use of memory.
   Now sets the 'Oversampling' option from the current state, rather than
    the configured default as we had been erroneously doing.
   Renamed application 'Bazound'.

0.04 (25th August 2003)
   Fixed stupid module version numbers in RMEnsure file.

0.05 (14th September 2003)
   Fixed stupid !Wimp file, which had been in the wrong format. This
    resulted in Bazound wasting time by constantly demanding null polls.

0.06 (21st September 2003)
   Reduced the maximum amount of memory requested in the !Run file, which
    was unnecessarily high (accidentally left from debuggging).

-----------------------------------------------------------------------------
5   Licence and Disclaimer
    ======================

  This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public Licence as published by the Free
Software Foundation; either version 2 of the Licence, or (at your option)
any later version.

  This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public Licence for
more details.

  You should have received a copy of the GNU General Public Licence along
with this program; if not, write to the Free Software Foundation, Inc.,
675 Mass Ave, Cambridge, MA 02139, USA.

  If you did not receive source code with this program then you can download
it from http://www.bigfoot.com/~chrisbazley/ . To rebuild the program you
will also need the BASIC libraries supplied with AppBasic.

-----------------------------------------------------------------------------
6   Credits
    =======

  Bazound was designed and programmed by Chris Bazley.

  AppBasic is (C) Joe Taylor. It is available from
      http://www.jettons.co.uk/riscos/toolbox/

  Olaf Krumnow and Herbert zur Nedden of the German Archimedes Group wrote
the ResFind program that is used to find the correct Help text for different
languages.

  The application icon was designed by Marko Lukats. It is the default one
given to all new applications created using AppBasic.

-----------------------------------------------------------------------------
7   Contact details
    ===============

  Feel free to contact me with any bug reports, suggestions or anything else.

  Mail:  Mr C.J. Bazley
         43 Wilton Grove
         Wimbledon
         London
         SW19 3QU

  Email: mailto:chrisbazley@bigfoot.com (preferred)
         mailto:chris@bazley.freeuk.com

  WWW:   http://www.bigfoot.com/~chrisbazley/
